package com.ikingtech.framework.sdk.role.api;

import com.ikingtech.framework.sdk.base.model.BatchParam;
import com.ikingtech.framework.sdk.base.model.DragOrderParam;
import com.ikingtech.framework.sdk.core.response.R;
import com.ikingtech.framework.sdk.role.model.RoleDTO;
import com.ikingtech.framework.sdk.role.model.RoleMenuUpdateParamDTO;
import com.ikingtech.framework.sdk.role.model.RoleQueryParamDTO;
import com.ikingtech.framework.sdk.role.model.RoleUserUpdateParamDTO;
import com.ikingtech.framework.sdk.web.annotation.PostRequest;
import io.swagger.v3.oas.annotations.Parameter;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;

import java.util.List;
import java.util.Map;

/**
 * 角色管理模块
 *
 * @author tie yan
 */
public interface RoleApi {

    /**
     * Adds a new role.
     *
     * @param role The role information to be added.
     * @return The result of the add operation.
     */
    @PostRequest(order = 1, value = "/add", summary = "新增", description = "新增，新增成功后返回编号。")
    R<String> add(@Parameter(name = "role", description = "角色信息")
                  @RequestBody RoleDTO role);

    /**
     * Deletes a role.
     *
     * @param id The ID of the role to be deleted.
     * @return The result of the delete operation.
     */
    @PostRequest(order = 2, value = "/delete", summary = "删除", description = "删除。")
    R<Object> delete(@Parameter(name = "id", description = "编号")
                     @RequestBody String id);

    /**
     * Updates a role.
     *
     * @param role The updated role information.
     * @return The result of the update operation.
     */
    @PostRequest(order = 3, value = "/update", summary = "更新", description = "更新。")
    R<Object> update(@Parameter(name = "role", description = "角色信息")
                     @RequestBody RoleDTO role);

    /**
     * Retrieves roles using pagination.
     *
     * @param queryParam The query parameters for the role search.
     * @return The list of roles retrieved.
     */
    @PostRequest(order = 4, value = "/list/page", summary = "分页查询", description = "分页查询，没有查询结果时返回空列表。")
    R<List<RoleDTO>> page(@Parameter(name = "queryParam", description = "查询条件")
                          @RequestBody RoleQueryParamDTO queryParam);

    /**
     * Retrieves all roles.
     *
     * @return The list of all roles.
     */
    @PostRequest(order = 5, value = "/list/all", summary = "全量查询", description = "全量查询，没有查询结果时返回空列表。")
    R<List<RoleDTO>> all();

    /**
     * Retrieves the details of a role.
     *
     * @param id The ID of the role to retrieve.
     * @return The details of the role.
     */
    @PostRequest(order = 6, value = "/detail/id", summary = "查询详情", description = "查询详情，数据不存在时仍然返回成功,数据为null。")
    R<RoleDTO> detail(@Parameter(name = "id", description = "编号")
                      @RequestBody String id);

    /**
     * Updates the menu assignment for a role.
     *
     * @param roleMenu The role menu assignment information.
     * @return The result of the update operation.
     */
    @PostRequest(order = 6, value = "/menu/update", summary = "更新角色菜单分配信息", description = "更新角色菜单分配信息。")
    R<Object> updateRoleMenu(@Parameter(name = "roleMenu", description = "角色菜单分配信息")
                             @RequestBody RoleMenuUpdateParamDTO roleMenu);

    /**
     * Assigns a role to a user.
     *
     * @param updateParam The role user update information.
     * @return The result of the assignment operation.
     */
    @PostRequest(order = 6, value = "/user/add", summary = "分配角色用户", description = "分配角色用户。")
    R<Object> addRoleUser(@Parameter(name = "updateParam", description = "角色用户更新信息")
                          @RequestBody RoleUserUpdateParamDTO updateParam);

    /**
     * Removes a role from a user.
     *
     * @param updateParam The role user update information.
     * @return The result of the removal operation.
     */
    @PostRequest(order = 6, value = "/user/remove", summary = "移除角色用户", description = "移除角色用户。")
    R<Object> removeRoleUser(@Parameter(name = "updateParam", description = "角色用户更新信息")
                             @RequestBody RoleUserUpdateParamDTO updateParam);

    /**
     * Retrieves roles based on multiple role IDs.
     *
     * @param ids The collection of role IDs.
     * @return The list of roles retrieved.
     */
    @PostRequest(order = 8, value = "/list/ids", summary = "查询角色(多角色编号)", description = "查询角色(多角色编号)，没有查询结果时返回空列表。")
    R<List<RoleDTO>> listByIds(@Parameter(name = "ids", description = "角色编号集合")
                               @RequestBody BatchParam<String> ids);

    /**
     * Retrieves roles as a map based on multiple role IDs.
     *
     * @param ids The collection of role IDs.
     * @return The map of roles retrieved.
     */
    @PostRequest(order = 9, value = "/map/ids", summary = "查询角色Map(多角色编号)", description = "查询角色Map(多角色编号)，没有查询结果时返回空Map。")
    R<Map<String, RoleDTO>> mapByIds(@Parameter(name = "ids", description = "角色编号集合")
                                     @RequestBody BatchParam<String> ids);

    /**
     * Retrieves menu IDs as a map based on multiple role IDs.
     *
     * @param roleIds The collection of role IDs.
     * @return The map of menu IDs retrieved.
     */
    @PostRequest(order = 9, value = "/menu-id/map/ids", summary = "查询菜单Map(多角色编号)", description = "查询菜单Map(多角色编号)，没有查询结果时返回空列表。")
    R<Map<String, List<String>>> mapMenuIdsByIds(BatchParam<String> roleIds);

    /**
     * Performs drag and drop sorting of roles.
     *
     * @param dragParam The drag and drop parameters.
     * @return The result of the drag and drop operation.
     */
    @PostRequest(order = 10, value = "/drag", summary = "拖拽排序", description = "拖拽排序，调用拖拽排序接口后需再次调用列表查询接口展示最新排序结果。")
    R<Object> drag(@Parameter(name = "dragParam", description = "拖拽参数。")
                   @RequestBody DragOrderParam dragParam);

    /**
     * Retrieves roles based on name.
     *
     * @param name The name of the role.
     * @return The list of roles retrieved.
     */
    @PostMapping("/list/name")
    R<List<RoleDTO>> listByName(String name);
}
